CKM_UNWRAP_TR31
This section provides a summary of CKM_UNWRAP_TR31.
Note
This mechanism is only available if you are using PTK 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.
Supported operations
Operation | Supported |
---|---|
Encrypt and Decrypt | No |
Sign and Verify | No |
SignRecover and VerifyRecover | No |
Digest | No |
Generate Key/Key-Pair | No |
Wrap and Unwrap | Unwrap |
Derive | No |
FIPS Mode support
Available in FIPS Mode | Restrictions in FIPS Mode |
---|---|
No | Not applicable |
Key size range (bytes) and parameters
Key size minimum/maximum | Value |
---|---|
Minimum | 16 |
Maximum | 32 |
Parameter
None
Mechanism description
The CKM_UNWRAP_TR31 mechanism is used to import a new key to a token where the wrapped key format is described by ASC X9 TR 31-2018: Interoperable Secure Key Exchange Key Block Specification (Date Registered: April 15, 2018) and X9.143-2021. The base key, also known as the key block protection key (KBPK), must be a symmetric key of type CKK_DES2, CKK_DES3, or CKK_AES and match the algorithm implied by the Key Block Version ID. The KBPK must contain a CKA_MECHANISM_LIST attribute with CKM_UNWRAP_TR31 specified.
CKM_UNWRAP_TR31 contributes the following attributes to the new key object based on the content of the TR-31 header:
- CKA_CLASS
-
CKO_SECRET_KEY if Algorithm = A, D, H, T
CKO_PRIVATE_KEY or CKO_PUBLIC_KEY if Algorithm = E, R, S
Note
Key blocks which contain asymmetric key types (RSA, DSA, or ECDSA) normally hold key pairs and therefore may unwrap to a CKO_PUBLIC_KEY or CKO_PRIVATE_KEY object. By default the CKO_PRIVATE_KEY class object is created, but the caller can specify that a CKO_PUBLIC_KEY object be created by setting the CKA_CLASS attribute in the new objects template.
- CKA_KEY_TYPE
-
CKK_AES if Algorithm = A
CKK_DES if Algorithm = D
CKK_ECDSA if Algorithm = E
CKK_GENERIC_SECRET if Algorithm = H
CKK_RSA if Algorithm = R
CKK_DSA if Algorithm = S
CKK_DES2 or CKK_DES3 if Algorithm = T (depending on key size recovered)
Usage attributes may be specified in the user template but must match the allowed attributes listed in the table below or be equal to False; that is, you cannot set an attribute to True unless it is allowed in the key block header.
Cryptoki usage attributes are allowed based on the TR-31 header Key Usage and Mode of Use fields, as shown in the following list:
- B3
-
Definition
Key derivation key (non-ANSI X9.24)
Allowed attribute
CKA_DERIVE = True if Mode = X
Note
If the 'DA' optional block is present then the CKA_DERIVE will be forced False.
- D0
-
Definition
Symmetric data encryption
Allowed attribute
CKA_ENCRYPT = True if Mode = B or E
CKA_DECRYPT = True if Mode = B or D
- D1
-
Definition
Asymmetric data encryption
Allowed attribute
CKA_ENCRYPT = True if Mode = B or E
CKA_DECRYPT = True if Mode = B or D
- K0
-
Definition
Key encryption or wrapping
Allowed attribute
CKA_WRAP = True if Mode = B or E
CKA_UNWRAP = True if Mode = B or D
- K1
-
Definition
TR-31 key block protection key
Allowed attribute
CKA_WRAP = True if Mode = B or E
CKA_UNWRAP = True if Mode = B or D
CKA_MECHANISM_LIST = CKM_WRAP_TR31_DERIVE + CKM_WRAP_TR31_VARIANT and/or CKM_UNWRAP_TR31 + CKM_UNWRAP_TR31_DISCARD
- K2
-
Definition
Asymmetric key pair (KRD) ANSI X9.139/TR-34
Allowed attribute
CKA_ENCRYPT = True if Mode = B or E
CKA_DECRYPT = True if Mode = B or D
- K3
-
Definition
Asymmetric key for key agreement/key wrapping
Allowed attribute
CKA_WRAP = True if Mode = B or E
CKA_UNWRAP = True if Mode = B or D
CKA_DERIVE = True if Mode = X
- K4
-
Definition
Key block protection key, ISO 20038
Allowed attribute
CKA_WRAP = True if Mode = B or E
CKA_UNWRAP = True if Mode = B or D
CKA_MECHANISM_LIST = CKM_WRAP_TR31_DERIVE + CKM_WRAP_TR31_VARIANT and/or CKM_UNWRAP_TR31 + CKM_UNWRAP_TR31_DISCARD
- M0, M1, M2, M3, M4, M5, M6, M7, M8
-
Definitions
ISO 16609 MAC algorithm 1 (using TDEA)
ISO 9797-1 MAC algorithm 1
ISO 9797-1 MAC algorithm 2
ISO 9797-1 MAC algorithm 3
ISO 9797-1 MAC algorithm 4
ISO 9797-1999 MAC algorithm 5
ISO 9797-1:2011 MAC Algorithm 5/CMAC HMAC
ISO 9797-1:2011 MAC Algorithm 6
Allowed attributes
CKA_SIGN = True if Mode = C or G
CKA_VERIFY = True if Mode = C or V
Note
If an HMAC key is specified and a 'HM' (HMAC mechanism) optional block is included, then a CKA_MECHANISM_LIST attribute with two mechanisms is added by the HSM based on the HM value. See the table below for the list of mechanism pairs.
- S0
-
Definition
Asymmetric key pair for digital signature
Allowed attribute
CKA_SIGN and CKA_SIGN_RECOVER = True if Mode = S
CKA_VERIFY and CKA_VERIFY_RECOVER = True if Mode = V
- S1
-
Definition
Asymmetric key pair, CA key
Allowed attribute
CKA_SIGN = True if Mode = S
CKA_VERIFY = True if Mode = V
- S2
-
Definition
Asymmetric key pair (non-X9.42)
Allowed attribute
CKA_SIGN and CKA_SIGN_RECOVER = True if Mode = S or T
CKA_VERIFY and CKA_VERIFY_RECOVER = True if Mode = V
CKA_DECRYPT = True if Mode = T or D or B
CKA_ENCRYPT = True if Mode = E or B
CKA_WRAP = True if Mode = E or B
CKA_UNWRAP = True if Mode = D or B
The table below lists the mechanism pairs added by the HSM if an HMAC key and 'HM' optional block are included. Mechanism pairs are listed by HM value. If the HM value is not recognized, CKR_MECHANISM_PARAM_INVALID is returned. Mechanisms may be recognized but not supported.
HM value | 1st mechanism in list | 2nd mechanism in list |
---|---|---|
'10' | CKM_SHA_1_HMAC | CKM_SHA_1_HMAC_GENERAL |
'20' | CKM_SHA224_HMAC | CKM_SHA224_HMAC_GENERAL |
'21' | CKM_SHA256_HMAC | CKM_SHA256_HMAC_GENERAL |
'22' | CKM_SHA384_HMAC | CKM_SHA384_HMAC_GENERAL |
'23' | CKM_SHA512_HMAC | CKM_SHA512_HMAC_GENERAL |
The following mechanisms are not supported by the HSM
HM value | 1st mechanism in list | 2nd mechanism in list |
---|---|---|
'24' | CKM_SHA512_224_HMAC | CKM_SHA512_224_HMAC_GENERAL |
'25' | CKM_SHA512_256_HMAC | CKM_SHA512_256_HMAC_GENERAL |
'30' | CKM_SHA3_224_HMAC | CKM_SHA3_224_HMAC_GENERAL |
'31' | CKM_SHA3_256_HMAC | CKM_SHA3_256_HMAC_GENERAL |
'32' | CKM_SHA3_384_HMAC | CKM_SHA3_384_HMAC_GENERAL |
'33' | CKM_SHA3_512_HMAC | CKM_SHA3_512_HMAC_GENERAL |
The following attributes will have the specified default values but may be overridden by the attribute template supplied to the mechanism:
Attribute type | Default value |
---|---|
CKA_TOKEN | False |
CKA_PRIVATE | False |
CKA_SENSITIVE | True1 |
CKA_MODIFIABLE | False2 |
CKA_LABEL | <empty> |
CKA_ID | <empty> |
CKA_START_DATE, CKA_END_DATE | <empty> |
1 Cannot be set False if the No Clear PINs security flag is set.
2 Cannot be set True
CKA_MECHANISM_LIST can only be specified in the template if the mechanism does not also want to contribute this attribute; that is, the user cannot override the default attribute shown in the table above.
CKA_EXTRACTABLE is defaulted as specified by the header Exportability byte but may be forced False by the caller.
Exportability byte | CKA_EXTRACTABLE default |
---|---|
E | True |
N | False |
S | True |
CKA_LOCAL, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE will be set False.
Key block optional blocks that are not otherwise mentioned in this specification are ignored by the HSM.
Return to ProtectToolkit-C mechanisms.